home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1999 July / Macworld (1999-07).dmg / Shareware World / Info / For Developers / Mops 3.4.sea / Quick Edit ƒ / Subject Glossary / OOP < prev    next >
Text File  |  1998-01-13  |  17KB  |  403 lines
  1.  \ 14Jan96 DBH
  2. CLASS DEFINITION
  3.  
  4. :CLASS    --  : name  super{ cname1 cname2 } opt
  5.     Begins definition of a new class.  One or more classnames can be 
  6.     designated as superclass(es).  There are optional parameters that may 
  7.     also be declared after the superclass list, including n INDEXED, LARGE, 
  8.     and GENERAL.  
  9. ;CLASS    --    Ends definition of a class.
  10.  
  11. SUPER{    --  : cname1 cname2 } opt
  12.     Used to declare the superclass(es) when defining a class. See :class.
  13.     
  14. SUPER>    ( -- : classname )    Oop    Class
  15.     Used in a class definition with multiple inheritiance.
  16.     Usage is: msg: super> someSuper.  someSuper is the name of
  17.     a superclass.  Will assure that the named method of the
  18.     named superclass will be used rather than that from the
  19.     default left to right class search order.  Replaces
  20.     supers_to_skip syntax.
  21.  
  22. TEMP    ( -- )    Oop    Class
  23.     ALternate syntax for TEMP{.
  24.  
  25. TEMP{    ( -- )    Oop    Class
  26.     Used within a definition or local section.
  27.     Declares a temporary object list.  Subsequently instantiated objects
  28.     in the list will exist only within the definition.  They also get a
  29.     release: message automatically when the definition exits (either at the 
  30.     semicolon or via EXIT).  If you call a definition recursively, you will
  31.     get a fresh copy of any temporary objects.  Example syntax is:
  32.         : SomeWord
  33.             temp{    int        anInt
  34.                     var        aVar
  35.                     string    aString  }
  36.     Optionally one can use TEMP { ... }.
  37.  
  38. GENERAL    --
  39.     Obsolete.  Do not use.
  40.     Optional class declaration that will allow late binding when this class 
  41.     is used as an ivar.  But note that GENERAL classes may not be used to 
  42.     map ivars to Mac toolbox calls because the class header information will 
  43.     be included.  INDEXED classes are automatically GENERAL.  
  44. LARGE    --
  45.     Sets the "large" option on an indexed class, allowing the number of 
  46.     elements to be greater than 32K.  
  47. INDEXED    n --
  48.     Sets a class and its subclasses to indexed, of element byte width n.  
  49.     Used after the superclass declaration list when defining a new class.  
  50.     Note that when instantiating an indexed class, you MUST precede the 
  51.     instance name with the number of elements you wish that instance to 
  52.     have.  Also note that all indexed classes are automatically declared to 
  53.     be GENERAL, so you may not used indexed classes to map into toolbox 
  54.     calls.  Also, n must be < 32K (see LARGE).  
  55.  
  56. :M    --  : name:
  57.     Begins definition of a method within a class.  Note that name: MUST end 
  58.     with a colon (:).  
  59. ;M    --    Ends definition of a method in a class.
  60.  
  61. PRIVATE    --
  62.     Use within a class definition.  Makes the following methods private—that 
  63.     is, they will be accessible from within this class or any of its 
  64.     subclasses, but not from anywhere else.  The criterion is simply that a 
  65.     call to Self of Super may access a private method, but nothing else can.  
  66.     Note that for this reason you can't late-bind to a private method, even 
  67.     if you do it from within the class itself.  
  68. PUBLIC    --
  69.     Applies to ivars and/or methods.
  70.     Makes the following methods public—that is, they will be accessible from 
  71.     anywhere.  PRIVATE and PUBLIC may be used any number of times within the 
  72.     one class definition.  Methods are initially public when a class 
  73.     compilation starts.
  74.     Also, ivars can be accessed from outside the class.  They're declared this way:
  75.         class myClass super{ mySuper }
  76.             public
  77.                 var    aVar
  78.                 int    anInt
  79.             end_public
  80.                 var anotherVar
  81.                 int    anotherInt
  82.     They're accessed from outside the class via this syntax:
  83.        msg: ivar> anIvar IN someObject
  84.     (where someObject is an object of myClass, of course).
  85.  
  86. END_PUBLIC    ( -- )    OOP    Class
  87.     Delimits end of a PUBLIC ivar list.  See PUBLIC.
  88.   
  89. RECORD{    ( -- )    Toolbox    Class
  90.     Alternate syntax for RECORD, but you cannot name the record.
  91.  
  92. RECORD    ( -- : name )    Toolbox    Class
  93.     The name is optional
  94.     Used in a class ivar list declaration.  Subsequently declared ivars
  95.     can be used to map into a Mac toolbox record because object header
  96.     information will not be there.  Note that you can not late bind to
  97.     an ivar in a RECORD{ list.  See also RECORD{.  Usage is as follows:
  98.         record <name>        \ The name is optional
  99.        {    var        v1
  100.             int        i1
  101.        }
  102.             string    s
  103.  
  104. CLASS_AS>    ( -- : classname )    OOP    Class
  105.     Mops allows you a shortcut way of sending a message to an object whose address is 
  106.     on the stack at run time, but with early binding.  You can do this with an objPtr, but it's also 
  107.     possible to say simply 
  108.         <obj addr on stack>  msg: someClass
  109.     in which case an early bind is compiled to the addressed object, ASSUMED to be of the class 
  110.     "someClass".  For those who do sometimes give their classes less than ideal names, there's now a new syntax 
  111.     for the above operation: 
  112.         <obj addr on stack>  msg: class_as> someClass
  113.     The old way will still work - I don't plan to delete it and maybe break existing code - but the new 
  114.     way reads less ambiguously (and compiles exactly the same code).  
  115.  
  116. IN_CLASS    ( -- : classname )    OOP    Class
  117.     If you combine the PUBLIC and STATIC ivar features, you can
  118.     get a "public static" ivar.  To access this from outside the
  119.     class, you can't use the IVAR> syntax since there's no object
  120.     to refer to.  So the syntax is: 
  121.         msg: ivar> aStaticIvar IN_CLASS myClass
  122.  
  123. IN    ( -- : objectname )    OOP    DebugMOD.txt
  124.     Used to access a public ivar from outside the class.
  125.     Usage is as follows:
  126.        msg: ivar> anIvar IN someObject
  127.     (where someObject is an object of myClass, of course).
  128.     See PUBLIC.
  129.  
  130. IVAR>    ( -- : ivarname )    OOP    Class
  131.     Used to access a public ivar from outside the class.
  132.     Usage is as follows:
  133.        msg: ivar> anIvar IN someObject
  134.     (where someObject is an object of myClass, of course).
  135.     See PUBLIC.
  136.  
  137. END_PUBLIC    ( -- )    OOP    Class
  138.     Delimits end of a PUBLIC ivar list.  See PUBLIC.
  139.  
  140. STATIC    ( -- )    OOP    Class
  141.     These are like static class variables in C++ - they belong to the class,
  142.     not the object, and thus are shared by all objects of the class.
  143.     Or you can use  static{ ...  } if you prefer.
  144.     The syntax for accessing them is just the same as for normal ivars.
  145.     They're declared like this:
  146.         class myClass super{ mySuper }
  147.             var    oneVar
  148.         static
  149.         {    var    someVar
  150.             int    someInt
  151.         }
  152.             var anotherVar
  153.     In this example, someVar and someInt are static, oneVar and anotherVar are normal ivars.  In the 
  154.     methods of myClass, whenever you access someVar, you are accessing the SAME ivar, no matter what 
  155.     object you are in, and similarly for someInt.  
  156.  
  157. STATIC{    ( -- )    OOP    Class
  158.     Synonym for STATIC.
  159.  
  160. CallFirst    --  : methodname:
  161.     The next method definition will always execute the method indicated by 
  162.     methodname: BEFORE it is executed by a subclass.  Provides a way for 
  163.     superclasses to limit the extent to which subclasses may override a 
  164.     method.  
  165. CallLast    --  : methodname:
  166.     The next method definition will always execute the method indicated by 
  167.     methodname: AFTER it is executed by a subclass.  Provides a way for 
  168.     superclasses to limit the extent to which subclasses may override a 
  169.     method. 
  170.     
  171. SELF    -- obj
  172.     Object reference to self.  Only used in a class definition.  SELF is not 
  173.     necessarily the same as ^BASE, because of multiple inheritance.  
  174. SUPER    -- obj
  175.     Use within a class method definition to refer to self, an instance of 
  176.     the class, but the superclass method will be invoked.  
  177.  
  178.  
  179. LATE BINDING
  180. [    --
  181.     Begins an expression with a late bound message that computes the address 
  182.     of the object to recieve the message.  e.g.  get: [ 0 at: anArray ] .  
  183.     This is an alternative syntax to that provided by **, [], and [self].  
  184. ]    --  See above.
  185.  
  186. note that [SELF], [], and ** are all synonyms.
  187. [SELF]    obj selid --
  188.     Late binds whatever is on the stack to the given method.  e.g.  obj 
  189.     get: [self] .  You must be sure that obj really does point to an 
  190.     object. 
  191. []    ^obj selid --    See above.
  192. **    ^obj selid --    See above.
  193.  
  194.  
  195. STANDARD METHODS
  196.  
  197. CLASSINIT:    --
  198.     Our standard constructor method.  The default message that is ALWAYS 
  199.     sent to an object at time of instantiation, even ivars.  Note that if 
  200.     parameters are to be included for a classinit: for an INDEXED class, the 
  201.     #elements must precede those parameters (#elems must be top item on 
  202.     stack) at instantiation time (read that again).  Note that for class 
  203.     object classinit: is a null method, that is it does nothing.  
  204.  
  205. ADDR:    -- ^base    
  206.     Returns the address of the beginning of an object's ivars.
  207. CLASS:    -- class    Returns the class pointer for an object.
  208. COPYTO:    obj --
  209.     Copies the ivar part of the passed in object to self.  Doesn't check 
  210.     type - be careful.  
  211. DUMP:    --    Performs a formatted dump of a class.
  212. LENGTH:    -- len
  213.     Gets total length of object.  Length will include class header 
  214.     information only if class is of type GENERAL.  Otherwise, length is 
  215.     merely the length of the ivar data field(s).  
  216. PRINT:    --        Use to display a class, default is just a DUMP:.
  217. RELEASE:    --
  218.     Our standard destructor method.  Any objects that allocate heap storage 
  219.     will redefine this appropriately.  Our convention is that an object will 
  220.     release ALL its storage when it gets a release: message.  Other methods 
  221.     can be provided to partly release storage, as needed.  
  222.  
  223.  
  224.  
  225. CONSOLE INSPECTION
  226.  
  227. .CLASS:    --    A method.  Prints the name of the class of the given object.
  228. .ID:    --    A method.  Prints the name of the given object, if it has a name.
  229.  
  230.  
  231. MISCELLANEOUS
  232.  
  233. BYTES    n --  : ivarname
  234.     Bytes is used as the ivar allocation primitive for basic classes.  
  235.     Allocates n bytes as a named instance variable of an object.  You can 
  236.     use bytes to map a Toolbox data structure as an object when named access 
  237.     to some of the fields is not needed (but you must know the proper 
  238.     length).  
  239.  
  240. BIND_WITH    obj --<selector> obj-modified  cfa
  241.     If you are late-binding in a loop, it can be much faster if you do the 
  242.     bind just once, then reuse the resulting cfa each time in the loop.  
  243.     This way you only have to perform the method search once.  To bind 
  244.     initially and get the cfa, use BIND_WITH.  Usage: (saveCfa and ^obj-mod 
  245.     are values or locals).  (get object's address) bind_with someSelector: 
  246.     -> saveCfa -> ^obj-mod.  (in the loop) ^obj-mod saveCfa ex-method.  
  247. SET_CLASS    obj theClass --
  248.     SET_CLASS is a utility word used to patch nucleus objects when their 
  249.     classes are defined in higher-level files.  Actually it could be used to 
  250.     change the class of any object, if anyone is silly enough to want to do 
  251.     that.  
  252. SET_TO_CLASS    objPtr --  : cname
  253.     If you need to declare the object pointer before the class exists, use 
  254.     SET_TO_CLASS once the class is defined, thus: ' someOP set_to_class 
  255.     someClass.  
  256.  
  257.  
  258. STANDARD CLASSES
  259.  
  260. (COL)    --  : name
  261.     Collections are ordered lists with a current size.  We implement them by 
  262.     multiply inheriting the generic (COL) class with the array class of the 
  263.     appropriate width.  We use a few tricks to avoid late binding to self in 
  264.     loops.  
  265. ARRAY    #elems --  : name
  266.     The basic 4-byte cell one-dimension array.  Class is INDEXED.
  267. BOOL    --  : name
  268.     Subclass of byte.  Note that since the datalength of aMops class bool is 
  269.     1, this class should be used to map into a Toolbox record of type 
  270.     BOOLEAN.  
  271. BYTE    --  : name    A standard 1-byte variable class.
  272. DICADDR    --  : name
  273.     DICADDR is a relocatable dictionary address class - use to store 
  274.     non-executable dictionary addresses.  
  275. HANDLE    --  : name    The standard class for handles.
  276. HANDLEARRAY    #elems --  : name
  277.     HANDLEARRAY and HANDLELIST are for the implementation of collections of 
  278.     heap-based objects.  HandleArray has normal array properties.  Use 
  279.     HandleList if the number of elements may grow arbitrarily large, and if 
  280.     indexing isn't so important.  HandleArray also includes methods to allow 
  281.     the array to be used as a stack - needed for FileList.  
  282. HANDLELIST    #elems --  : name
  283. HANDLELIST allows the implementation of a list of heap-based objects.  
  284.     Unlike HANDLEARRAY, the list can be of indefinite length.  We use a heap 
  285.     block to store the handles to the objects contiguously, rather than have 
  286.     a separate block for each handle and link them together.  This saves on 
  287.     memory overhead and reduces the number of memory manager calls.  It also 
  288.     reflects the assumption that insertions and deletions into the middle of 
  289.     the list will be infrequent, as these could be more inefficient than 
  290.     with a linked scheme.  We expect that elements will normally be added to 
  291.     the end, and probably not removed at all, or not very often.  
  292. INDEXED-OBJ    --  : name
  293.     Class INDEXED-OBJ is the generic superclass for all arrays.  Here we 
  294.     define the general indexed methods, which apply regardless of indexed 
  295.     width.  
  296. LONGWORD    --  : name    Generic superclass for var, handle etc.
  297. OBJHANDLE    --  : name
  298.     An OBJHANDLE is a handle that points to an object in the heap.
  299. OBJPTR    --  :  name
  300.     An object pointer is a "low-level" entity, rather like a value.  The 
  301.     syntax for object pointers is: objPtr anObjptr class_is theClass 
  302. OBJ_ARRAY    #elems --  : name
  303.     OBJ_ARRAY is a generic superclass which makes it easy to generate an 
  304.     array of objects of a given class.  Just define a new class which 
  305.     multiply inherits from the given class (or classes) and OBJ_ARRAY (which 
  306.     must come last).  This will add an indexed section to each object of the 
  307.     new class, with elements wide enough to contain objects of the original 
  308.     class.  Then SELECT: "switches in" the selected element to be the 
  309.     "current" element, and all the normal methods of the class can then be 
  310.     used.  Note the use of"32767 indexed" in the class definition.  
  311. ORDERED-COL    #elems --  : name
  312.     Ordered-Collection is a collection of 4-byte cells.  A subclass of (col) 
  313.     and array.  
  314. PTR    --   : name    A standard class.  For toolbox pointers.
  315. RESOURCE    --   : name
  316.     Provides basic support for Toolbox resources.
  317. SEQUENCE    #elems -- j  : name
  318.     A generic superclass for classes which have multiple items which 
  319.     frequently need to be looked at in sequence.  At present the main 
  320.     function of Sequence is to implement the EACH: method, which makes it 
  321.     very simple to deal with each element.  Sequence can be multiply 
  322.     inherited with any class which implements the FIRST?: and NEXT?: 
  323.     methods.  The actual implementation details are quite irrelevant, as 
  324.     long as these methods are supported.  
  325. VAR    --   : name
  326.     The standard variable class.  Subclass of longword that adds the +: and 
  327.     -: methods.  Useful as an ivar that maps into a Toolbox LONGINT record 
  328.     structure.  
  329. X-ADDR    --   : name
  330.     X-ADDR is an executable dictionary address class.  The only significant 
  331.     difference to DicAddr is that there is an Exec: method and no Get: 
  332.     method.  But if we ever have to separate code and data, having a 
  333.     separate class could prove very useful.  
  334. X-ARRAY    #elems --   : name
  335.     A subclass of ARRAY, can execute its elements (which are cfas of Mops 
  336.     words).  
  337. X-COL    #elems --   : name
  338.     X-COL is a collection of executable word addresses.  A subclass of (col) 
  339.     and x-array.  
  340.  
  341.  
  342. PRIMITIVES
  343.  
  344. ^BASE    -- addr
  345.     Addr is the base address of the private data of the object.  Only used 
  346.     in a class definition.  Same as addr: self.  
  347. OBJ    -- obj
  348.     Called from within an inline method.  Passes the object's base and 
  349.     displacement to Handlers to generate the correct address.  Optimization 
  350.     will then apply.  
  351. OBJECT    -- class
  352.     The root class of all classes.  Only used as a declared superclass when 
  353.     defining a new class.  Note that class object has the pre-defined 
  354.     methods class:, .id:, .class:, addr:, length:, copyto:, classinit:, 
  355.     release:, dump:, and print:.  So ALL objects possess these methods.  
  356.     Some of these methods do nothing, for class object.  
  357. OBJLEN    -- n    Computes total data length of current object.
  358. CHKSAME    obj -- obj
  359.     A check that two objects are of exactly the same class.  Aborts with 
  360.     error message if not.  
  361. CHKCLASS    cfa -- cfa
  362. Aborts and issues error message if the cfa does not refer to a class.  
  363. ?>CLASS    obj -- class
  364.     Converts the pointer to an object to a pointer to its class.  Aborts if 
  365.     failure.  
  366. ?CLASS    --    Error if not compiling a class definition.
  367. CL1    --    Cleans up the class compiler data on an abort.
  368. CL>LEN    #els class -- #els len
  369.     Gets data length of object given #els and class.
  370. DFA    class -- dfa
  371.     Given a pointer to a class, returns the data field address.  First 2 
  372.     bytes are the data length, second 2 bytes are the width of the indexed 
  373.     elements.  
  374. DLEN&XWID    class -- dlen xwid
  375.     Given a class pointer, retuns the ivar datalength and width of the 
  376.     indexed elements.  
  377. EXMID    obj selID --
  378.     Executes a method given its sel ID.  Used in late binding.
  379. FFA    ^class -- ffa
  380.     Given a pointer to a class, returns the flag field address.
  381. FINDM    selID class -- offs cfa    Finds a method in a class.
  382. GETDLEN    obj -- n    Gets length of object's named ivars.
  383. IFA    class -- ifa
  384.     Given a pointer to a class, returns the ivar field address.
  385. IVFINDM    selID ^ivar -- offs cfa    Looks for a method in
  386. IX    -- ifa
  387.     Called from within an inline method.  Compiles code to generate the 
  388.     indexed address.  
  389. META    -- class
  390.     META is the super class of Object - top of all inheritance.
  391. MFA    class -- mfa    Given a pointer to a class, returns the methods field address.
  392. RELCNT    -- n
  393.     A value.  For testing - counts release: msgs to make sure we're 
  394.     releasing everything.  
  395. SFA    class -- sfa
  396.     Given a pointer to a class, returns the superclass field address, which 
  397.     is an N-way pointer.  
  398. SUPER(    --  : cname1 cname2 } opt    Synonym for super{.
  399. XWID    class -- xwid    Given a class pointer, retuns the width of the indexed elements.
  400. ^CLASS    -- class    Addr of the class we're currently compiling.
  401. ^DLEN    obj -- dfa    Returns the dfa for the given object.
  402. ^ELEM    idx -- addr    Leaves addr of indexed element.
  403.